/*
 *	Routines to manage notifier chains for passing status changes to any
 *	interested routines. We need this instead of hard coded call lists so
 *	that modules can poke their nose into the innards. The network devices
 *	needed them so here they are for the rest of you.
 *
 *				Alan Cox <Alan.Cox@linux.org>
 */
 
#ifndef _LINUX_NOTIFIER_H
#define _LINUX_NOTIFIER_H
#include <linux/errno.h>
/*notifer_block 数据结构。对于网卡设备而言，网卡
设备的启动和关闭是事件。内核中某些模块需要得到这些事件的通知从而采取相应的措施。
这是通过主动通知的方式完成的。当事件发生时，事件通知者遍历系统中某个队列，调用感
兴趣者注册的函数，从而通知这些感兴趣者。要得到事件的通知，首先必须表示对这些事件
的兴趣，而要表示对某个事件感兴趣，首先必须注册这个“兴趣”，而 notifer_block 结构就
表示一个“兴趣”。一般一个队列本身表示某种类型的事件，对此种类型事件感兴趣者注册
到这个队列中，就表示了其兴趣所在。当事件发生时，该队列中所有的感兴趣者之前注册的
函数将被调用，从而得到对事件发生的通知。*/
struct notifier_block
{
	// 感兴趣者注册的被调用函数。当注册的感兴趣事件发生时，事件通知者将调用该函数以通知感兴趣者。
	int (*notifier_call)(unsigned long, void *);
	struct notifier_block *next;
	int priority;	// 优先级
};


#ifdef __KERNEL__
// 这四个常量用于表示何时终止对感兴趣者队列中注册函数的调用
#define NOTIFY_DONE		0x0000		/* Don't care */ // 通知完成，此后即便队列还有尚未被通知到的感兴趣者，依然停止通知操作。
#define NOTIFY_OK		0x0001		/* Suits me */	// 继续进行通知直到队列尾部
#define NOTIFY_STOP_MASK	0x8000		/* Don't call further */ // 位掩码，用于判断返回值	 
#define NOTIFY_BAD		(NOTIFY_STOP_MASK|0x0002)	/* Bad/Veto action	*/ // 某个感兴趣者出现问题，停止通知队列中其它感兴趣者

// 用于感兴趣者进行注册事件发生时被调用的函数从而得到事件发生通知
// 表示感兴趣者的 notifier_block 结构根据其优先级插入到系统某个队列中
extern __inline__ int notifier_chain_register(struct notifier_block **list, struct notifier_block *n)
{
	while(*list)
	{
		if(n->priority > (*list)->priority)
			break;
		list= &((*list)->next);
	}
	n->next = *list;
	*list=n;
	return 0;
}

/*
 *	Warning to any non GPL module writers out there.. these functions are
 *	GPL'd
 */
 // 撤销对某类事件的兴趣，也即将表示兴趣的相应 notifier_block 结构从相应队列中删除
extern __inline__ int notifier_chain_unregister(struct notifier_block **nl, struct notifier_block *n)
{
	while((*nl)!=NULL)
	{
		if((*nl)==n)
		{
			*nl=n->next;
			return 0;
		}
		nl=&((*nl)->next);
	}
	return -ENOENT;
}

/*
 *	This is one of these things that is generally shorter inline
 */
 // 当事件发生时完成对感兴趣者的通知。通知方式即调用感兴趣者之前注册的函数。
extern __inline__ int notifier_call_chain(struct notifier_block **n, unsigned long val, void *v)
{
	int ret=NOTIFY_DONE;
	struct notifier_block *nb = *n;
	while(nb)
	{
		ret=nb->notifier_call(val,v);
		if(ret&NOTIFY_STOP_MASK)
			return ret;
		nb=nb->next;
	}
	return ret;
}


/*
 *	Declared notifiers so far. I can imagine quite a few more chains
 *	over time (eg laptop power reset chains, reboot chain (to clean 
 *	device units up), device [un]mount chain, module load/unload chain,
 *	low memory chain, screenblank chain (for plug in modular screenblankers) 
 *	VC switch chains (for loadable kernel svgalib VC switch helpers) etc...
 */
 
/* netdevice notifier chain */ // 三种网卡事件
#define NETDEV_UP	0x0001	/* For now you can't veto a device up/down */
#define NETDEV_DOWN	0x0002
#define NETDEV_REBOOT	0x0003	/* Tell a protocol stack a network interface
				   detected a hardware crash and restarted
				   - we can use this eg to kick tcp sessions
				   once done */
#endif
#endif
